packages/clerk-js/src/core/clerk.ts (1)

1201-1220: Avoid unsafe cast when resolving session by ID

Blindly asserting the found session to SignedInSessionResource can hide bugs and accidentally sign users out when an invalid session ID is passed. Fail fast with a clear error instead.

Apply this diff:

-      if (typeof session === 'string') {
-        session = (this.client.sessions.find(x => x.id === session) as SignedInSessionResource) || null;
-      }
+      if (typeof session === 'string') {
+        const foundSession = this.client.sessions.find(x => x.id === session);
+        if (!foundSession) {
+          throw new Error(`setActive: Session with ID "${session}" not found.`);
+        }
+        session = foundSession as SignedInSessionResource;
+      }

packages/clerk-js/src/core/sessionTasks.ts (3)

16-16: Add explicit return type to getTaskEndpoint

Internal or not, exported helpers should declare return types for clarity and to avoid accidental widening.

-export const getTaskEndpoint = (task: SessionTask) => `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`;
+export const getTaskEndpoint = (task: SessionTask): string =>
+  `/tasks/${INTERNAL_SESSION_TASK_ROUTE_BY_KEY[task.key]}`;

---

21-31: Bug: forwarded params placed outside hash; also missing redirectUrl propagation and explicit return type

Task pages are hash-routed. Passing forwarded params via top-level searchParams leaks them outside the hash. Also, the open item to preserve redirectUrl is not implemented, and the function lacks an explicit return type.

Apply all three fixes:

• Use hashSearchParams (not searchParams).
• Accept optional redirectUrl and append it (as redirect_url) to hash params.
• Add explicit return type.

-export function buildTaskUrl(task: SessionTask, opts: Pick<Parameters<typeof buildURL>[0], 'base'>) {
-  const params = forwardClerkQueryParams();
-
-  return buildURL(
-    {
-      base: opts.base,
-      hashPath: getTaskEndpoint(task),
-      searchParams: params,
-    },
-    { stringify: true },
-  );
-}
+export function buildTaskUrl(
+  task: SessionTask,
+  opts: { base: string; redirectUrl?: string },
+): string {
+  const params = forwardClerkQueryParams();
+  if (opts.redirectUrl) {
+    // keep in the hash to survive SPA hash routing
+    params.set('redirect_url', opts.redirectUrl);
+  }
+  return buildURL(
+    {
+      base: opts.base,
+      hashPath: getTaskEndpoint(task),
+      hashSearchParams: params,
+    },
+    { stringify: true },
+  ) as string;
+}

---

37-53: Propagate redirectUrl and add explicit return type in navigateIfTaskExists

When a session has a pending task, navigation should preserve the original redirectUrl. The function should also declare its return type.

-export function navigateIfTaskExists(
-  session: SessionResource,
-  {
-    navigate,
-    baseUrl,
-  }: {
-    navigate: (to: string) => Promise<unknown>;
-    baseUrl: string;
-  },
-) {
+export function navigateIfTaskExists(
+  session: SessionResource,
+  {
+    navigate,
+    baseUrl,
+    redirectUrl,
+  }: {
+    navigate: (to: string) => Promise<unknown>;
+    baseUrl: string;
+    redirectUrl?: string;
+  },
+): Promise<unknown> | void {
   const currentTask = session.currentTask;
   if (!currentTask) {
     return;
   }
 
-  return navigate(buildTaskUrl(currentTask, { base: baseUrl }));
+  return navigate(buildTaskUrl(currentTask, { base: baseUrl, redirectUrl }));
 }

packages/clerk-js/src/ui/components/SignUp/index.tsx (1)

5-5: Missing TypeScript path alias configuration

The @/ui/hooks/usePreloadTasks import will fail because tsconfig.json doesn't define a @/* path mapping. Add the required path alias configuration or revert to relative imports.

-import { usePreloadTasks } from '@/ui/hooks/usePreloadTasks';
+import { usePreloadTasks } from '../../hooks/usePreloadTasks';

#!/bin/bash
# Verify that TypeScript path mapping for @/ exists
fd -t f "tsconfig.*\.json$" -x cat {} \; | jq -r '.compilerOptions.paths' 2>/dev/null | grep -q '"@/\*"'
if [ $? -eq 0 ]; then
  echo "Path mapping for @/ exists"
else
  echo "Path mapping for @/ does NOT exist"
fi

packages/clerk-js/src/ui/contexts/components/SignIn.ts (2)

32-34: Update return type and make redirectUrl optional in type definition

The type definition should make redirectUrl optional and use Promise<void> for clarity since the navigation doesn't return meaningful data.

-  navigateOnSetActive: (opts: { session: SessionResource; redirectUrl: string }) => Promise<unknown>;
+  navigateOnSetActive: (opts: { session: SessionResource; redirectUrl?: string }) => Promise<void>;

---

123-133: navigateOnSetActive should respect provider-level taskUrls configuration

The function doesn't check for custom task URLs from the ClerkProvider configuration. According to the documented precedence rules, provider-level taskUrls should take priority over default task navigation paths.

 const navigateOnSetActive = async ({ session, redirectUrl }: { session: SessionResource; redirectUrl: string }) => {
   const currentTask = session.currentTask;
   if (!currentTask) {
     return navigate(redirectUrl || afterSignInUrl);
   }
 
+  // Check for custom task URL from provider configuration
+  const customTaskUrl = clerk.__internal_getOption('taskUrls')?.[currentTask.key];
+  if (customTaskUrl) {
+    return navigate(customTaskUrl);
+  }
+
   const taskEndpoint = getTaskEndpoint(currentTask);
   const taskNavigationPath = isCombinedFlow ? '/create' + taskEndpoint : taskEndpoint;
 
   return navigate(`/${basePath}${taskNavigationPath}`);
 };

packages/types/src/clerk.ts (3)

123-123: Add comprehensive JSDoc for SetActiveNavigate public API type

This public API type needs documentation explaining its purpose, parameters, and usage. Also refine the return type for better type safety.

-export type SetActiveNavigate = ({ session }: { session: SessionResource }) => Promise<unknown>;
+/**
+ * Callback function invoked by `setActive` just before committing the active session/organization.
+ * Use it to implement custom navigation for pending session tasks.
+ *
+ * When provided, this callback takes precedence over `redirectUrl`.
+ *
+ * @param ctx.session - The session that is about to become active. It may contain a `currentTask`.
+ * @returns Optionally return a promise to allow awaiting asynchronous router operations.
+ *
+ * @example
+ * await clerk.setActive({
+ *   session,
+ *   navigate: async ({ session }) => {
+ *     const task = session.currentTask;
+ *     if (task) {
+ *       await router.push(`/tasks/${task.key}`);
+ *       return;
+ *     }
+ *     await router.push('/dashboard');
+ *   },
+ * });
+ */
+export type SetActiveNavigate = (ctx: { session: SessionResource }) => Promise<void> | void;

---

678-682: Add JSDoc documentation for buildTasksUrl public API method

This new public API method needs comprehensive documentation.

+  /**
+   * Returns the configured URL where session tasks are mounted, based on the current
+   * session's task and configured taskUrls.
+   * 
+   * @returns The URL for the current session task, or an empty string if no task exists
+   * 
+   * @example
+   * const taskUrl = clerk.buildTasksUrl();
+   * // Returns something like: '/sign-in#/tasks/choose-organization'
+   */
   buildTasksUrl(): string;

---

770-774: Add JSDoc documentation for redirectToTasks public API method

This new public API method needs comprehensive documentation.

+  /**
+   * Redirects to the configured URL where session tasks are mounted.
+   * Uses the URL generated by `buildTasksUrl()`.
+   * 
+   * @returns A promise that resolves when navigation is complete
+   * 
+   * @example
+   * await clerk.redirectToTasks();
+   * // Navigates to the appropriate task URL for the current session
+   */
   redirectToTasks(): Promise<unknown>;

packages/clerk-js/src/core/__tests__/clerk.test.ts (4)

447-457: Type cast mismatch: using PendingSessionResource in active session test

This test is in the "with active session status" suite but casts to PendingSessionResource. Either move the test to the pending session suite or fix the cast to match the test context.

-await sut.setActive({ session: mockSession as any as PendingSessionResource, navigate });
+await sut.setActive({ session: mockSession as any as ActiveSessionResource, navigate });

---

547-548: Type cast should be PendingSessionResource, not ActiveSessionResource

The test verifies behavior for pending sessions but incorrectly casts to ActiveSessionResource.

-await sut.setActive({ session: mockSession as any as ActiveSessionResource });
+await sut.setActive({ session: mockSession as any as PendingSessionResource });

---

560-560: Type cast should be PendingSessionResource for consistency

Same casting issue - the test is for pending session behavior but uses ActiveSessionResource.

-await sut.setActive({ session: mockSession as any as ActiveSessionResource });
+await sut.setActive({ session: mockSession as any as PendingSessionResource });

---

564-578: Add test coverage for navigate callback precedence and redirectUrl preservation

The test suite should verify:

1. When both navigate callback and taskUrls are provided, the callback takes precedence
2. redirectUrl passed to setActive is preserved in the navigation URL

Add these test cases after the existing "navigate to taskUrl option" test:

it('prefers navigate callback over taskUrls when both are provided', async () => {
  mockSession.touch.mockReturnValue(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockSession] }));
  const navigate = jest.fn();

  const sut = new Clerk(productionPublishableKey);
  sut.navigate = jest.fn();
  await sut.load({
    taskUrls: {
      'choose-organization': '/choose-organization',
    },
  });
  await sut.setActive({ session: mockSession as any as PendingSessionResource, navigate });
  expect(mockSession.touch).toHaveBeenCalled();
  expect(navigate).toHaveBeenCalled();
  expect(sut.navigate).not.toHaveBeenCalled();
});

it('preserves redirectUrl when navigating to taskUrl', async () => {
  mockSession.touch.mockReturnValue(Promise.resolve());
  mockClientFetch.mockReturnValue(Promise.resolve({ signedInSessions: [mockSession] }));

  const sut = new Clerk(productionPublishableKey);
  sut.navigate = jest.fn();
  await sut.load({
    taskUrls: {
      'choose-organization': '/choose-organization',
    },
  });
  await sut.setActive({ 
    session: mockSession as any as PendingSessionResource, 
    redirectUrl: '/dashboard' 
  });
  expect(mockSession.touch).toHaveBeenCalled();
  // Verify the URL includes the redirect parameter
  expect(sut.navigate).toHaveBeenCalledWith(
    expect.stringContaining('redirect_url=/dashboard')
  );
});

packages/clerk-js/src/core/clerk.ts (2)

1851-1873: Preserve redirectUrl and honor provider overrides during OAuth task navigation

Current setActiveNavigate drops redirectUrl and ignores provider-level taskUrls. Build the final URL locally and append redirectUrl to hash or query appropriately.

Apply this diff:

     const signInUrl = params.signInUrl || displayConfig.signInUrl;
     const signUpUrl = params.signUpUrl || displayConfig.signUpUrl;

-    const setActiveNavigate = async ({
-      session,
-      baseUrl,
-      redirectUrl,
-    }: {
-      session: SessionResource;
-      baseUrl: string;
-      redirectUrl: string;
-    }) => {
-      if (!session.currentTask) {
-        await this.navigate(redirectUrl);
-        return;
-      }
-
-      await navigateIfTaskExists(session, {
-        baseUrl,
-        navigate: this.navigate,
-      });
-    };
+    const setActiveNavigate = async ({
+      session,
+      baseUrl,
+      redirectUrl,
+    }: {
+      session: SessionResource;
+      baseUrl: string;
+      redirectUrl: string;
+    }) => {
+      if (!session.currentTask) {
+        await this.navigate(redirectUrl);
+        return;
+      }
+      const customTaskUrl = this.#options.taskUrls?.[session.currentTask.key];
+      let to =
+        customTaskUrl ??
+        (buildURL({ base: baseUrl, hashPath: getTaskEndpoint(session.currentTask) }, { stringify: true }) as string);
+      if (redirectUrl) {
+        const useHash = to.includes('#');
+        const buildOpts: Record<string, unknown> = { base: to };
+        if (useHash) {
+          buildOpts.hashSearchParams = { redirectUrl };
+        } else {
+          buildOpts.searchParams = { redirectUrl };
+        }
+        to = buildURL(buildOpts, { stringify: true }) as string;
+      }
+      await this.navigate(to);
+    };

---

1310-1337: Fix duplicate navigation, preserve redirectUrl correctly, and guard navigate callback errors

• Duplicate navigation: redirectUrl is navigated twice (with auth and then without).
• redirectUrl preservation: always appending as hash params breaks path-based URLs.
• Consumer callback safety: exceptions from setActive.navigate can skip state restoration.

Apply this diff:

       if (!beforeEmit && (redirectUrl || taskUrl || setActiveNavigate)) {
         await tracker.track(async () => {
           if (!this.client) {
             // Typescript is not happy because since thinks this.client might have changed to undefined because the function is asynchronous.
             return;
           }

           if (newSession?.status !== 'pending') {
             this.#setTransitiveState();
           }

           if (taskUrl) {
-            const taskUrlWithRedirect = redirectUrl
-              ? buildURL({ base: taskUrl, hashSearchParams: { redirectUrl } }, { stringify: true })
-              : taskUrl;
-            await this.navigate(taskUrlWithRedirect);
+            let taskUrlWithRedirect = taskUrl;
+            if (redirectUrl) {
+              const useHash = taskUrl.includes('#');
+              const buildOpts: Record<string, unknown> = { base: taskUrl };
+              if (useHash) {
+                buildOpts.hashSearchParams = { redirectUrl };
+              } else {
+                buildOpts.searchParams = { redirectUrl };
+              }
+              taskUrlWithRedirect = buildURL(buildOpts, { stringify: true }) as string;
+            }
+            await this.navigate(taskUrlWithRedirect);
           } else if (setActiveNavigate && newSession) {
-            await setActiveNavigate({ session: newSession });
+            try {
+              await setActiveNavigate({ session: newSession });
+            } catch (err) {
+              logger.error('Clerk.setActive navigate callback failed', err);
+            }
           } else if (redirectUrl) {
-            if (this.client.isEligibleForTouch()) {
+            if (this.client.isEligibleForTouch()) {
               const absoluteRedirectUrl = new URL(redirectUrl, window.location.href);
               const redirectUrlWithAuth = this.buildUrlWithAuth(
                 this.client.buildTouchUrl({ redirectUrl: absoluteRedirectUrl }),
               );
               await this.navigate(redirectUrlWithAuth);
-            }
-            await this.navigate(redirectUrl);
+            } else {
+              await this.navigate(redirectUrl);
+            }
           }
         });
       }

packages/clerk-js/src/core/sessionTasks.ts (3)

9-11: Tighten the mapping type with satisfies (safer than assertion)

Avoids unnecessary assertion and ensures future task keys must be added.

-export const INTERNAL_SESSION_TASK_ROUTE_BY_KEY: Record<SessionTask['key'], string> = {
-  'choose-organization': 'choose-organization',
-} as const;
+export const INTERNAL_SESSION_TASK_ROUTE_BY_KEY = {
+  'choose-organization': 'choose-organization',
+} satisfies Record<SessionTask['key'], string>;

---

55-69: Type the function return as void for clarity

Minor: make the intent explicit and align with TS best practices for exported helpers.

-export function warnMissingPendingTaskHandlers(options: Record<string, unknown>) {
+export function warnMissingPendingTaskHandlers(options: Record<string, unknown>): void {
   const taskOptions = ['taskUrls', 'navigate'] as Array<
     keyof (Pick<SetActiveParams, 'navigate'> & Pick<ClerkOptions, 'taskUrls'>)
   >;

---

21-31: Add tests to cover redirectUrl preservation and hash param placement

Please add unit tests that assert:

• buildTaskUrl returns URLs with forwardClerkQueryParams and redirect_url inside the hash, not top-level query.
• navigateIfTaskExists preserves redirectUrl when provided.

Do you want me to scaffold these tests (Jest + URL parsing assertions) for sessionTasks?

Also applies to: 37-53

packages/clerk-js/src/ui/components/SignUp/SignUpVerificationCodeForm.tsx (1)

56-59: Improve error handling consistency

Catching and directly rejecting loses localized error handling. Use the existing handleError + translateError mechanisms used in other UI components to surface errors consistently.

For example: call handleError(err) and/or pass errors back through VerificationCodeCard controls rather than raw reject().

packages/clerk-js/src/ui/contexts/components/SignIn.ts (1)

123-133: Consider making redirectUrl optional and memoizing the callback

The redirectUrl parameter should be optional since it may not always be provided to setActive. Additionally, memoizing the callback would prevent unnecessary re-renders in consuming components.

+import { createContext, useContext, useMemo, useCallback } from 'react';
// ... existing imports

-const navigateOnSetActive = async ({ session, redirectUrl }: { session: SessionResource; redirectUrl: string }) => {
+const navigateOnSetActive = useCallback(
+  async ({ session, redirectUrl }: { session: SessionResource; redirectUrl?: string }) => {
     const currentTask = session.currentTask;
     if (!currentTask) {
-      return navigate(redirectUrl);
+      return navigate(redirectUrl || afterSignInUrl);
     }
 
     const taskEndpoint = getTaskEndpoint(currentTask);
     const taskNavigationPath = isCombinedFlow ? '/create' + taskEndpoint : taskEndpoint;
 
     return navigate(`/${basePath}${taskNavigationPath}`);
-  };
+  },
+  [navigate, basePath, isCombinedFlow, afterSignInUrl]
+);

packages/types/src/clerk.ts (1)

1208-1229: Document the precedence of navigate over redirectUrl

The JSDoc should explicitly mention that when both navigate and redirectUrl are provided, navigate takes precedence and redirectUrl is ignored.

   /**
    * A custom navigation function to be called just before the session and/or organization is set.
    *
-   * When provided, it takes precedence over the `redirectUrl` parameter for navigation.
+   * When provided, it takes precedence over the `redirectUrl` parameter for navigation.
+   * If both `navigate` and `redirectUrl` are specified, `redirectUrl` will be ignored.
    *
    * @example
    * ```typescript
    * await clerk.setActive({
    *   session,
+   *   redirectUrl: '/dashboard', // This will be ignored
    *   navigate: async ({ session }) => {
    *     const currentTask = session.currentTask;
    *     if (currentTask) {
    *       await router.push(`/onboarding/${currentTask.key}`)
    *       return
    *     }
    *
    *     router.push('/dashboard');
    *   }
    * });
    * ```
    */
   navigate?: SetActiveNavigate;

packages/clerk-js/src/core/clerk.ts (3)

1554-1574: Add JSDoc for new public API: buildTasksUrl

Public APIs must be documented. Add behavior, precedence, and a brief example.

Apply this diff:

+  /**
+   * Builds the URL for the current session task.
+   *
+   * Precedence:
+   * - If a provider-level `taskUrls` override exists for the current task key, that URL is returned.
+   * - Otherwise, returns a default hash-based tasks URL under the SignIn base.
+   *
+   * Returns an empty string when there is no current task.
+   *
+   * @public
+   * @returns {string}
+   * @example
+   * const to = clerk.buildTasksUrl();
+   * if (to) await clerk.navigate(to);
+   */
   public buildTasksUrl(): string {

---

1666-1672: Add JSDoc for new public API: redirectToTasks

Document behavior and that it no-ops outside the browser.

Apply this diff:

-  public redirectToTasks = async (): Promise<unknown> => {
+  /**
+   * Navigates to the current session task URL, if any.
+   * No-ops on non-browser environments.
+   *
+   * @public
+   * @returns {Promise<unknown>}
+   */
+  public redirectToTasks = async (): Promise<unknown> => {

---

1201-1356: Tests needed for new after-auth flows and edge cases

Add/extend tests to cover:

• setActive().navigate precedence vs taskUrls
• redirectUrl propagation for both hash and path routes
• error handling when navigate callback throws
• SSO/Web3 flows navigating to tasks with provider overrides

Do you want me to draft unit/integration tests for these cases (including hash vs query preservation)? I can propose Jest/Vitest test scaffolding aligned with existing suites.

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

Learnt from: LauraBeatris
PR: clerk/javascript#6486
File: packages/clerk-js/src/core/clerk.ts:1303-1344
Timestamp: 2025-08-08T19:00:08.988Z
Learning: In Clerk's navigation system for pending sessions, `taskUrls` (configured at the ClerkProvider level) should take priority over the `navigate` callback (from All-In-One components). This ensures that explicit provider-level configuration overrides component-level navigation logic, providing developers with predictable control over navigation behavior.